Skip to content

Add opt-in extended activity tracking with activity_metrics entity#1467

Merged
Matus Tomlein (matus-tomlein) merged 4 commits intorelease/4.8.0from
feature/extended-activity-tracking
Apr 20, 2026
Merged

Add opt-in extended activity tracking with activity_metrics entity#1467
Matus Tomlein (matus-tomlein) merged 4 commits intorelease/4.8.0from
feature/extended-activity-tracking

Conversation

@stanch
Copy link
Copy Markdown
Contributor

Attach quantitative activity metrics (mouse distance, scroll distance, key presses, clicks, touches) to page_ping events when extendedActivityTracking is enabled. Reuses existing DOM event handlers with zero overhead when the feature is off.

Attach quantitative activity metrics (mouse distance, scroll distance,
key presses, clicks, touches) to page_ping events when
extendedActivityTracking is enabled. Reuses existing DOM event handlers
with zero overhead when the feature is off.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Copy link
Copy Markdown

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Adds an opt-in “extended activity tracking” mode to the Snowplow Browser Tracker so page pings can include quantitative interaction metrics (mouse distance, scroll distance, key presses, clicks, touches) via an activity_metrics context entity and via activity callback data.

Changes:

  • Introduces ActivityMetrics type and extendedActivityTracking configuration flag, and wires metric accumulation into activity/scroll handlers.
  • Attaches an activity_metrics self-describing entity to page ping contexts (and surfaces metrics on ActivityCallbackData).
  • Adds Jest coverage validating accumulation, reset behavior, and callback population.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 2 comments.

Show a summary per file
File Description
trackers/browser-tracker/src/api.ts Re-exports ActivityMetrics from the public browser-tracker API surface.
libraries/browser-tracker-core/src/tracker/types.ts Adds ActivityMetrics + extendedActivityTracking option and exposes metrics on callback data.
libraries/browser-tracker-core/src/tracker/schemata.ts Adds ACTIVITY_METRICS_SCHEMA constant.
libraries/browser-tracker-core/src/tracker/index.ts Implements metric accumulation, entity attachment, and lifecycle resets for extended tracking.
libraries/browser-tracker-core/test/tracker/extended_activity_tracking.test.ts Adds tests for metric accumulation/reset and callback exposure.
api-docs/docs/browser-tracker/browser-tracker.api.md Updates generated API docs for new types/config fields.
common/changes/@snowplow/browser-tracker/feature-extended-activity-tracking_2026-04-06-13-19.json Adds change entry for browser-tracker package.
common/changes/@snowplow/browser-tracker-core/feature-extended-activity-tracking_2026-04-06-13-19.json Adds change entry for browser-tracker-core package.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment thread libraries/browser-tracker-core/src/tracker/index.ts
Comment thread libraries/browser-tracker-core/src/tracker/index.ts Outdated
Comment thread api-docs/docs/browser-tracker/browser-tracker.api.md Outdated
Comment thread libraries/browser-tracker-core/src/tracker/index.ts Outdated
@matus-tomlein
Copy link
Copy Markdown
Contributor

This looks good, but could you please add something closer to an integration test in tracker.test.ts that would also check the entity being tracked?

Here is something that AI suggested, but whatever gets us closer to an integration test (probably extending the e2e browser tests we have would be too much complicated):

it('attaches activity_metrics entity to page ping payload when using callback with extendedActivityTracking', async () => {
  const ACTIVITY_METRICS_SCHEMA = 'iglu:com.snowplowanalytics.snowplow/activity_metrics/jsonschema/1-0-0';
  const state = new SharedState();
  const t =
    addTracker('sp8', 'sp8', '', '', state, {
      stateStorageStrategy: 'cookie',
      encodeBase64: false,
      customFetch,
      eventStore,
    }) ?? fail('Failed to create tracker');

  t.enableActivityTrackingCallback({
    minimumVisitLength: 0,
    heartbeatDelay: 10,
    extendedActivityTracking: true,
    callback: () => {},  // no-op — we're testing the payload, not the callback data
  });
  t.trackPageView();

  // advance 1s, fire two clicks, then complete the heartbeat window
  jest.advanceTimersByTime(1000);
  document.dispatchEvent(new MouseEvent('click'));
  document.dispatchEvent(new MouseEvent('click'));
  jest.advanceTimersByTime(9000);

  const events = await eventStore.getAllPayloads();
  const pings = getPPEvents(events);
  expect(F.size(pings)).toBe(1);

  const entities = JSON.parse(pings[0].co as string).data as Array<{ schema: string; data: any }>;
  const metricsEntity = entities.find((e) => e.schema === ACTIVITY_METRICS_SCHEMA);
  expect(metricsEntity).toBeDefined();
  expect(metricsEntity!.data.clicks).toBe(2);
});

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM!

@matus-tomlein Matus Tomlein (matus-tomlein) changed the base branch from master to release/4.8.0 April 20, 2026 08:21
@matus-tomlein Matus Tomlein (matus-tomlein) merged commit 89c42c6 into release/4.8.0 Apr 20, 2026
6 of 7 checks passed
Matus Tomlein (matus-tomlein) pushed a commit that referenced this pull request Apr 20, 2026
…1467)

* Add opt-in extended activity tracking with activity_metrics entity

Attach quantitative activity metrics (mouse distance, scroll distance,
key presses, clicks, touches) to page_ping events when
extendedActivityTracking is enabled. Reuses existing DOM event handlers
with zero overhead when the feature is off.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Add change files

* Add API extractor changes

* Address review feedback

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

3 participants